Skip to content

feat(tools): 台帳への行追加を支援する add_row.py を追加 - #1896

Merged
mhaya merged 2 commits into
develop_v2.0.4from
chore/api-inventory-add-row
Aug 24, 2026
Merged

feat(tools): 台帳への行追加を支援する add_row.py を追加#1896
mhaya merged 2 commits into
develop_v2.0.4from
chore/api-inventory-add-row

Conversation

@mhaya

@mhaya mhaya commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

概要 (Summary)

台帳（API インベントリ）に行を追加する作業を支援するツールを追加します。ツールとドキュメントのみで、アプリケーションコードへの変更はありません。

reconcile.py が「インベントリ未収載」を検出しても、57列を手で並べる必要があり実務的ではありませんでした。add_row.py は api_snapshot.json（実機 url_map）と git から機械的に決まる列を埋め、調査が要る列に TODO を入れた雛形を出力します。

変更タイプ (Type of Change)

  • 🚀 新機能追加 (Feature) — 開発基盤
  • 📚 仕様書・マニュアル・APIリストの更新 (Documentation)

使い方

export WEKO_API_INVENTORY_DIR=/path/to/weko-secret

# 雛形を確認（まだ書き込まない）
python3 tools/api-inventory/scripts/add_row.py --endpoint api:weko_admin.foo
python3 tools/api-inventory/scripts/add_row.py --uri /api/items/import-task

# 追記する
python3 tools/api-inventory/scripts/add_row.py --endpoint api:weko_admin.foo --append

自動で埋まる列 / 埋めない列

列
自動（27列） no / module / api_type / app / method / uri / path_params / blueprint / endpoint / impl_func / impl_file / impl_line / auth_required / auth_method / auth_mechanism / api_version / last_commit系4列 ほか
TODO（31列） summary / response / status_codes / roles / data_op / data_target / data_store / side_effects / config_deps / test_file / notes / sec_* / dynamic_verified / csrf_protection ほか

TODO はソースを読まないと書けない列です。Phase 2（静的解析）と Phase 3（実機実測）でやっていることを、その1行について行います。

派生列（priority / test_* / cleanup）は空のままでよく、後続の test_coverage.py → prioritize.py が付与します。

ドキュメント

scripts/README.md の「台帳の更新手順」ケース2を、この手順に沿って具体化しました。あわせて次を明記しています。

  • ケース2b（既存行の修正）を分離し、派生列は手編集しても次の実行で消えること
  • TODO を残したままにすると prioritize.py の入力が欠け、誤った優先度が付くこと（例: data_op が TODO だと破壊系の判定に入らない）

動作検証

$ add_row.py --endpoint api:weko_admin.get_curr_api_cert
  自動で埋まる列: 27  /  TODO(要調査): 31

$ add_row.py --uri /records/replace_file
  no=927 / module=weko-records-ui / api_type=画面ビュー / app=UIアプリ / method=POST

--uri は API アプリのルールが url_map 上 /api を含まない（DispatcherMiddleware でマウントされるため）点を考慮し、前置してから比較しています。

注意

台帳そのものは public な本リポジトリに含まれていません。このツールは WEKO_API_INVENTORY_DIR が指す秘密の場所の台帳を読み書きします（未設定なら理由を添えて中断します）。

mhaya and others added 2 commits August 24, 2026 22:43
@mhaya @claude
feat(tools): 台帳への行追加を支援する add_row.py を追加
9d32ad9 
reconcile が未収載を検出しても、57列を手で並べる必要があり実務的でなかった。
api_snapshot.json(実機url_map)と git から機械的に決まる27列を埋め、調査が要る
31列に TODO を入れた雛形を出力する。--append で full.tsv に追記する。

  自動: no/module/api_type/app/method/uri/path_params/blueprint/endpoint/
        impl_func/impl_file/impl_line/auth_required/auth_method/auth_mechanism/
        api_version/last_commit系4列 ほか
  TODO: summary/data_op/dynamic_verified/sec_* など、ソースを読まないと書けない列

scripts/README.md のケース2を、この手順に沿って具体化した。あわせてケース2b
(既存行の修正)を分け、派生列は手編集しても消えることを明記した。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXo9u6PoTf6VRKr3aiGvZ3
@mhaya @claude
fix(tools): 機械付与スクリプトの入出力を直し、既存値を保護する
c6d8b72 
add_cols.py / add_ssrf_redirect.py / add_idempotency.py / add_dataop4.py /
add_authmech.py は当時の中間ファイル運用の名残で、入出力が
R+"weko3_api_list.tsv"(24列版)にハードコードされていた。いま実行すると
台帳を壊す状態だったため、$WEKO_API_INVENTORY_DIR の full.tsv を
in-place 更新するようにした(第1引数でも指定可)。

参照する列位置(c[2]=api_type, c[4]=method, c[13]=impl_file, c[14]=impl_line,
c[20]=auth_required, c[21]=auth_method)は現行 full.tsv と一致しており変更不要。

既存列は「その位置のまま値を差し替える」方式にした。末尾に付け直すと列順が
変わり、README の awk 例や他スクリプトの列位置前提が壊れるため。

さらに **空欄/TODO のセルだけを埋める**ようにした。台帳の既存値は機械出力
そのままではなく後から精査されており、一括再生成すると劣化することを実測で
確認したため(bola_risk の判定が逆転、data_op_detail の論理/物理の区別が失われる、
csrf_protection の指摘が消える)。意図的に作り直すときは
WEKO_INVENTORY_OVERWRITE=1 を指定する。

あわせて「列数: N」の表示が古い計算式で実際と合っていなかったのを直した。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXo9u6PoTf6VRKr3aiGvZ3
@mhaya
mhaya merged commit 91cde1d into develop_v2.0.4 Aug 24, 2026
29 of 95 checks passed
@mhaya mhaya mentioned this pull request Aug 24, 2026
Merged
2 tasks
@github-actions

github-actions Bot commented Aug 24, 2026

Copy link
Copy Markdown

API インベントリ差分（件数のみ）

明細は公開できないため件数のみ表示しています。該当箇所は秘密側の台帳・レポートで確認してください。

ベースラインとの差分

API インベントリ差分レポート

  • 旧: d2fdc0e3b v2.0.3 (profile=default) endpoints=860 (外部ライブラリ由来 291)
  • 新: 3a2f84da1 v2.0.3-16-g3a2f84da1 (profile=default) endpoints=860 (外部ライブラリ由来 291)

判定: ✅ PASS (FAIL 0 / WARN 1)

サマリ

分類 件数
ADDED 0
REMOVED 0
RULE_CHANGED 0
METHODS_CHANGED 0
AUTH_CHANGED 0
IMPL_CHANGED 0
ATTRS_UNKNOWN_NEW 0
ModelView 追加 0
ModelView 削除 0
ModelView フラグ変化 0
config 変化 0
コメントアウト認証の増加 0
依存パッケージの版変化 3

[WARN] W6 依存パッケージの版が変化した — 3件

  • pbr — 7.0.3 -> 7.1.1
  • pyld — 3.1.0 -> 3.2.0
  • weko-redis — 0.1.0.dev20170000 -> (削除)

台帳との突き合わせ

スナップショット ↔ インベントリ 突き合わせ

  • リビジョン: 3a2f84da1 v2.0.3-16-g3a2f84da1 経路URI=870
  • 台帳: 行=926 URI=881

件数のみ。詳細は秘密側の完全版レポートを参照。

判定: ✅ 一致 (0件)

検出 件数
A. インベントリ未収載(抽出漏れ) 0
B. 実機に無い(未説明) 0
B'. 実機に無い(既知・許容) 11
C. メソッド不一致 0
D. app列の不一致 0

@github-actions

github-actions Bot commented Aug 24, 2026

Copy link
Copy Markdown

API インベントリ差分（件数のみ）

明細は公開できないため件数のみ表示しています。該当箇所は秘密側の台帳・レポートで確認してください。

ベースラインとの差分

API インベントリ差分レポート

  • 旧: d2fdc0e3b v2.0.3 (profile=default) endpoints=860 (外部ライブラリ由来 291)
  • 新: f9ab71ebc v2.0.3-17-gf9ab71ebc (profile=default) endpoints=860 (外部ライブラリ由来 291)

判定: ✅ PASS (FAIL 0 / WARN 1)

サマリ

分類 件数
ADDED 0
REMOVED 0
RULE_CHANGED 0
METHODS_CHANGED 0
AUTH_CHANGED 0
IMPL_CHANGED 0
ATTRS_UNKNOWN_NEW 0
ModelView 追加 0
ModelView 削除 0
ModelView フラグ変化 0
config 変化 0
コメントアウト認証の増加 0
依存パッケージの版変化 3

[WARN] W6 依存パッケージの版が変化した — 3件

  • pbr — 7.0.3 -> 7.1.1
  • pyld — 3.1.0 -> 3.2.0
  • weko-redis — 0.1.0.dev20170000 -> (削除)

台帳との突き合わせ

スナップショット ↔ インベントリ 突き合わせ

  • リビジョン: f9ab71ebc v2.0.3-17-gf9ab71ebc 経路URI=870
  • 台帳: 行=926 URI=881

件数のみ。詳細は秘密側の完全版レポートを参照。

判定: ✅ 一致 (0件)

検出 件数
A. インベントリ未収載(抽出漏れ) 0
B. 実機に無い(未説明) 0
B'. 実機に無い(既知・許容) 11
C. メソッド不一致 0
D. app列の不一致 0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mhaya